/*
 *  SystemTransactionManager.java        22-ott-2009
 *   
 * Copyright (c) 2009 mentalsmash.org
 *  
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 * 
 *  http://www.apache.org/licenses/LICENSE-2.0
 * 
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 * 
 *  The use of the Apache License does not indicate that this project is
 *  affiliated with the Apache Software Foundation.
 */

package org.mentalsmash.tazio.transactions.control;

import java.util.concurrent.Future;

import org.mentalsmash.tazio.transactions.user.RollbackException;
import org.mentalsmash.tazio.transactions.user.Transaction;
import org.mentalsmash.tazio.transactions.user.TransactionStatus;
import org.mentalsmash.tazio.transactions.user.TransactionalSystemException;

/**
 * The <tt>SystemTransactionManager</tt> interface provides method for
 * transaction management to be used internally by the Transactional System.
 * Therefore this interface should not be exposed or used by clients of the
 * system
 * 
 * @author Andrea Reale
 * @version 0.0.1
 */
public interface SystemTransactionManager {

    /**
     * Complete the transaction associated to the current thread.
     * <p>
     * When this method completes the transaction is no longer associated to the
     * thread
     * <p>
     * 
     * @throws RollbackException
     * @throws TransactionStateException
     * @throws TransactionalSystemException
     */
    void commit() throws RollbackException, TransactionStateException,
	    TransactionalSystemException;

    /**
     * Start the commit of the transaction asynchronously.
     * <p>
     * Another thread takes the control to complete the commitment of the
     * transactions, and it reports the result through the use of the
     * {@link Future} object returned.
     * </p>
     * <p>
     * The transactions remains associated to the calling thread until a
     * positive or negative outcome about the commitment is reached.
     * </p>
     * 
     * @return
     * @throws TransactionStateException
     */
    Future<TransactionStatus> commitAsync() throws TransactionStateException;

    /**
     * Returns the status of the transaction, or
     * {@link TransactionStatus#NO_TRANSACTION} if there is no transaction
     * associated to the current thread
     * 
     * @return
     */
    TransactionStatus getStatus();

    /**
     * Returns the instance of {@link TransactionLog} which contains the
     * complete history of active and inactive transactions managed by this
     * instance of <tt>TransactionManager</tt>
     * 
     * @return
     */
    TransactionsLog getTransactionsLog();

    /**
     * Roll back the transaction associated with the current thread. When this
     * method completes, the thread is no longer associated with a transaction.
     * <p>
     * This method has no effect if the transaction is in one of the following
     * states:
     * <ul>
     * <li>COMMITTED</li>
     * <li>ROLLED_BACK</li>
     * </ul>
     * and it throws an exception if the current thread has no transaction
     * associated to it.
     * </p>
     * 
     * @throws TransactionStateException
     */
    void rollback() throws TransactionStateException;

    /**
     * Retrieves an instance of the validation agent used by the
     * {@link SystemTransactionManager}
     * 
     * @return an instance of the validation agent used by the
     *         {@link SystemTransactionManager}
     */
    ValidationAgent getValidationAgent();

    /**
     * Return the transaction associated with the calling thread.
     * <p>
     * This method should never return <code>null</code>: if there's no
     * transaction associated to the thread it creates a floating transaction
     * and associates it to the thread
     * </p>
     * 
     * @return
     */
    Transaction getTransaction();

}
